docs(holoscan-modules): add the pure-Python Module workflow to Create a Module by devin-ai-integration[bot] · Pull Request #19 · nvidia-holoscan/holoscan-tutorials

devin-ai-integration · 2026-11-06T21:23:22Z

Summary

Documents the Module features coming in holoscan-cli 5.1.0 in the "Create a Module" tutorial. The tutorial previously said Python-implemented operators and wheels were unsupported. The features are:

holoscan create --language python (holoscan-cli#284), with its operator layout from holoscan-cli#296;
wheels for Modules with Python bindings (holoscan-cli#275).

Hold until the next holoscan-cli release. The tutorial pins holoscan-cli[create]==5.1.0 as a placeholder; 5.0.0, the current release, has none of these features.

New §4.6 Implement operators in pure Python, covering:
- the hs.Input/hs.Output operator in operators/my_module_op/my_module_op.py and the graph (forward["in"]);
- adding an operator: add_holohub_operator() / OP_<name>, cmake.define.OP_<name>, and the TYPE_CHECKING import;
- holoscan build/run/test;
- an OperatorTestHarness test;
- holoscan install --dev --local;
- a CLI-free editable install that rebuilds on import (pip install --no-build-isolation -Ceditable.rebuild=true -e .);
- holoscan package ... --pkg-generator WHEEL, which produces a py3-none-any wheel depending on holoscan-core-cu13.
Old §4.6–4.11 become §4.7–4.12. The anchors that "Use a Module" links to (§3.2, §4.5) don't change.
§4.9 keeps the Debian package for C++ operators and adds --pkg-generator WHEEL for Python bindings, which produces a cp312-abi3-linux_<arch> wheel.
§1 and §2 describe C++ vs. Python operators and the pure-Python host requirements: Python 3.12+, glibc 2.39+, a CUDA 13 driver, and CMake 3.24+. They need no compiler or SDK Debian package.
§3.1 adds a cpp / cpp python / python table, and §3.3 adds the pure-Python tree.
The CI, publishing, reference card, and troubleshooting sections are updated, and so are the parent holoscan-modules/README.md requirements. The tutorial goes to 0.4.0.

Verification

All commands ran in holoscan:v5.0.0-cuda13 with CLI wheels built from holoscan-cli main and the #296 branch. There was no GPU, so a stub libcuda was used.

Module	Step	Result
`python`	`create`, `build`, `run --local`	Run printed `my_module_pipeline received 10 samples`
`python`	`test --local`	CTest passed: `python.my_module`
`python`	`install --dev --local`, then `--uninstall`	`import holoscan.my_module` worked, then failed after uninstall, as expected
`python`	`package --pkg-generator WHEEL --local`	Produced `py3-none-any` wheel
`python`	Documented editable install, `pytest tests/python`, edit an operator	3 tests passed; edit visible on next import
`cpp python`	`package --pkg-generator WHEEL --local`	Produced `cp312-abi3-linux_x86_64` wheel
`cpp python`	Fresh venv: install the wheel, `pip check`, `import holoscan.my_module`, run the Python pipeline	Pipeline ran

Pre-commit passed (lychee and nbcheck skipped), and lychee 0.24.2 run separately passed. Not verified: GPU, aarch64, and host-driven container commands.

Link to Devin session: https://nvidia-cloud.devinenterprise.com/sessions/e2d0e9d75b0b42f295b43491ae274a9d
Open in Devin Desktop: https://nvidia-cloud.devinenterprise.com/desktop/session/e2d0e9d75b0b42f295b43491ae274a9d?variant=devin

… a Module Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration · 2026-11-06T21:23:25Z

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

Disable automatic comment, CI, and merge conflict monitoring

tbirdso · 2026-11-06T21:45:40Z

+│   └── holoscan_my_module/
+│       └── operators/
+│           └── my_module_op.py   # Typed Input/Output class attributes
+├── operators/
+│   └── my_module_op/
+│       └── metadata.json         # Operator metadata only


I expected my_module_op.py implementation under the operators/my_module_op folder, not python/holoscan_my_module. Review and consider whether any changes are needed in the CLI template.

I reviewed this; the CLI template needs changes before the tutorial does.

Why the template uses python/holoscan_my_module/ today: it's the same package directory the cpp python bindings use. scikit-build-core packages it as a single directory (wheel.packages = ["python/holoscan_my_module"]), and operators/<op>/ keeps only metadata.json.

Moving the source to operators/my_module_op/my_module_op.py works. I tried it with scikit-build-core 1.0.3, mapping the directory into the package with the table form:

[tool.scikit-build.wheel.packages] "holoscan_my_module" = "python/holoscan_my_module" "holoscan_my_module/operators/my_module_op" = "operators/my_module_op"

The py3-none-any wheel contained the operator at holoscan_my_module/operators/my_module_op/.

pip install -e . picked up edits to operators/my_module_op/my_module_op.py without reinstalling.

from holoscan_my_module.operators import MyModuleOp stays the same if operators/my_module_op/__init__.py re-exports the class.

Template work this would need:

Generate operators/<op>/{__init__.py, <op>.py} and drop the copy under python/.

Add one wheel.packages entry per operator, plus wheel.exclude so metadata.json stays out of the wheel.

Make python/CMakeLists.txt stage operators/*/ into the build tree for holoscan build/run/test and install --dev.

Update the operator path that create prints, and the unit tests and generated docs.

Adding an operator later would also mean adding a wheel.packages line.

Recommendation: do it in a holoscan-cli follow-up PR before 5.1.0, so the released template matches the 4.x and C++ layout, where operator source sits next to its metadata.json. I'll update this tutorial's tree and §4.6 afterward. Should I open that CLI PR?

I opened holoscan-cli#296 as a draft to change the template. Operator source now lives in operators/<op>/<op>.py, with operators/__init__.py exporting every operator. The wheel and build tree install operators/ as holoscan_my_module.operators, and metadata.json stays out of the wheel.

I pushed 6be0057 here so the §3.3 tree and §4.6 match that layout. This PR now depends on #296 as well as the 5.1.0 release.

Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…tors/<op>/ Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…thon Modules Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

… operators Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

bhashemian

Two commands need to follow the updated CLI template before this draft is released. Details are inline. Validation was a static comparison against the upstream module templates; no SDK or hardware tests were run.

…omponent, uv group, and namespace Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

greptile-apps · 2026-11-13T14:47:16Z

Confidence Score: 5/5

[Low impact] The update appears safe to merge once the stated Holoscan CLI release hold is lifted.

Summary

Adds the pure-Python Module workflow and wheel packaging guidance to the Create a Module tutorial.

The tutorial shows how to build and package pure-Python Modules.
The tutorial shows how C++ operators can ship in a Python wheel.

Release hold: devin-ai-integration[bot] notes that publication must wait for Holoscan CLI 5.1.0; the pin is a placeholder until that release.

_{Reviews (2) · Last reviewed commit: "docs(holoscan-modules): separate PyPI ad..." · Reviewed by Greptile}

…ings wheels Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs(holoscan-modules): add the pure-Python Module workflow to Create…

aa47f7f

… a Module Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

tbirdso reviewed Nov 6, 2026

View reviewed changes

tbirdso and others added 3 commits November 6, 2026 21:49

docs(holoscan-modules): document wheels for Modules with Python bindings

d629687

Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs(holoscan-modules): show pure-Python operator sources under opera…

6be0057

…tors/<op>/ Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs(holoscan-modules): gate pure-Python operators on OP_<name>

8222ab1

Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

tbirdso mentioned this pull request Nov 6, 2026

refactor(create): keep pure-Python operator sources in operators/<op>/ nvidia-holoscan/holoscan-cli#296

Merged

tbirdso and others added 2 commits November 6, 2026 22:25

docs(holoscan-modules): use a rebuilding editable install for pure-Py…

6a28ecb

…thon Modules Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

docs(holoscan-modules): add type-checking imports for new pure-Python…

3eb2823

… operators Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

bhashemian reviewed Nov 13, 2026

View reviewed changes

Comment thread tutorials/holoscan-modules/create-a-module/README.md Resolved

Comment thread tutorials/holoscan-modules/create-a-module/README.md Resolved

docs(holoscan-modules): match the current Module template's install c…

6a46077

…omponent, uv group, and namespace Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

greptile-apps Bot reviewed Nov 13, 2026

View reviewed changes

Comment thread tutorials/holoscan-modules/create-a-module/README.md Resolved

docs(holoscan-modules): separate PyPI advice for pure-Python and bind…

9fbe3f9

…ings wheels Signed-off-by: Tom Birdsong <tbirdsong@nvidia.com> Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Navigation Menu

Repository navigation

docs(holoscan-modules): add the pure-Python Module workflow to Create a Module - #19

docs(holoscan-modules): add the pure-Python Module workflow to Create a Module#19
devin-ai-integration[bot] wants to merge 8 commits into
mainfrom
devin/1794000004-create-module-pure-python

devin-ai-integration Bot commented Nov 6, 2026 •

edited

Loading

Uh oh!

devin-ai-integration Bot commented Nov 6, 2026

Uh oh!

tbirdso Nov 6, 2026

Uh oh!

devin-ai-integration Bot Nov 6, 2026

Uh oh!

devin-ai-integration Bot Nov 6, 2026

Uh oh!

Uh oh!

bhashemian left a comment

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Nov 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

devin-ai-integration Bot commented Nov 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Uh oh!

devin-ai-integration Bot commented Nov 6, 2026

Uh oh!

tbirdso Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bhashemian left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Nov 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

devin-ai-integration Bot commented Nov 6, 2026 •

edited

Loading

greptile-apps Bot commented Nov 13, 2026 •

edited

Loading